<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="zh-CN" lang="zh-CN">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>

<title>Ruby on Rails 指南指导方针 — Ruby on Rails Guides</title>
<link rel="stylesheet" type="text/css" href="stylesheets/style.css" />
<link rel="stylesheet" type="text/css" href="stylesheets/print.css" media="print" />

<link rel="stylesheet" type="text/css" href="stylesheets/syntaxhighlighter/shCore.css" />
<link rel="stylesheet" type="text/css" href="stylesheets/syntaxhighlighter/shThemeRailsGuides.css" />

<link rel="stylesheet" type="text/css" href="stylesheets/fixes.css" />

<link href="images/favicon.ico" rel="shortcut icon" type="image/x-icon" />
</head>
<body class="guide">
  <div id="topNav">
    <div class="wrapper">
      <strong class="more-info-label">更多内容 <a href="http://rubyonrails.org/">rubyonrails.org:</a> </strong>
      <span class="red-button more-info-button">
        更多内容
      </span>
      <ul class="more-info-links s-hidden">
        <li class="more-info"><a href="http://weblog.rubyonrails.org/">博客</a></li>
        <li class="more-info"><a href="http://guides.rubyonrails.org/">指南</a></li>
        <li class="more-info"><a href="http://api.rubyonrails.org/">API</a></li>
        <li class="more-info"><a href="http://stackoverflow.com/questions/tagged/ruby-on-rails">提问</a></li>
        <li class="more-info"><a href="https://github.com/rails/rails">到 GitHub 贡献</a></li>
        <li class="more-info"><a href="https://ruby-china.org/">Ruby China 社区</a></li>
      </ul>
    </div>
  </div>
  <div id="header">
    <div class="wrapper clearfix">
      <h1><a href="index.html" title="返回首页">Rails 指南</a></h1>
      <ul class="nav">
        <li><a class="nav-item" href="index.html">首页</a></li>
        <li class="guides-index guides-index-large">
          <a href="index.html" id="guidesMenu" class="guides-index-item nav-item">指南索引</a>
          <div id="guides" class="clearfix" style="display: none;">
            <hr />
              <dl class="L">
                <dt>新手入门</dt>
                <dd><a href="getting_started.html">Rails 入门</a></dd>
                <dt>模型</dt>
                <dd><a href="active_record_basics.html">Active Record 基础</a></dd>
                <dd><a href="active_record_migrations.html">Active Record 迁移</a></dd>
                <dd><a href="active_record_validations.html">Active Record 数据验证</a></dd>
                <dd><a href="active_record_callbacks.html">Active Record 回调</a></dd>
                <dd><a href="association_basics.html">Active Record 关联</a></dd>
                <dd><a href="active_record_querying.html">Active Record 查询接口</a></dd>
                <dt>视图</dt>
                <dd><a href="layouts_and_rendering.html">Rails 布局和视图渲染</a></dd>
                <dd><a href="form_helpers.html">Action View 表单辅助方法</a></dd>
                <dt>控制器</dt>
                <dd><a href="action_controller_overview.html">Action Controller 概览</a></dd>
                <dd><a href="routing.html">Rails 路由全解</a></dd>
              </dl>
              <dl class="R">
                <dt>深入探索</dt>
                <dd><a href="active_support_core_extensions.html">Active Support 核心扩展</a></dd>
                <dd><a href="i18n.html">Rails 国际化 API</a></dd>
                <dd><a href="action_mailer_basics.html">Action Mailer 基础</a></dd>
                <dd><a href="active_job_basics.html">Active Job 基础</a></dd>
                <dd><a href="testing.html">Rails 应用测试指南</a></dd>
                <dd><a href="security.html">Ruby on Rails 安全指南</a></dd>
                <dd><a href="debugging_rails_applications.html">调试 Rails 应用</a></dd>
                <dd><a href="configuring.html">配置 Rails 应用</a></dd>
                <dd><a href="command_line.html">Rails 命令行</a></dd>
                <dd><a href="asset_pipeline.html">Asset Pipeline</a></dd>
                <dd><a href="working_with_javascript_in_rails.html">在 Rails 中使用 JavaScript</a></dd>
                <dd><a href="autoloading_and_reloading_constants.html">自动加载和重新加载常量</a></dd>
                <dd><a href="caching_with_rails.html">Rails 缓存概览</a></dd>
                <dd><a href="api_app.html">使用 Rails 开发只提供 API 的应用</a></dd>
                <dd><a href="action_cable_overview.html">Action Cable 概览</a></dd>
                <dt>扩展 Rails</dt>
                <dd><a href="rails_on_rack.html">Rails on Rack</a></dd>
                <dd><a href="generators.html">创建及定制 Rails 生成器和模板</a></dd>
                <dt>为 Ruby on Rails 做贡献</dt>
                <dd><a href="contributing_to_ruby_on_rails.html">为 Ruby on Rails 做贡献</a></dd>
                <dd><a href="api_documentation_guidelines.html">API 文档指导方针</a></dd>
                <dd><a href="ruby_on_rails_guides_guidelines.html">Ruby on Rails 指南指导方针</a></dd>
                <dt>维护方针</dt>
                <dd><a href="maintenance_policy.html">Ruby on Rails 的维护方针</a></dd>
                <dt>发布记</dt>
                <dd><a href="upgrading_ruby_on_rails.html">Ruby on Rails 升级指南</a></dd>
                <dd><a href="5_0_release_notes.html">Ruby on Rails 5.0 发布记</a></dd>
                <dd><a href="4_2_release_notes.html">Ruby on Rails 4.2 发布记</a></dd>
                <dd><a href="4_1_release_notes.html">Ruby on Rails 4.1 发布记</a></dd>
                <dd><a href="4_0_release_notes.html">Ruby on Rails 4.0 发布记</a></dd>
                <dd><a href="3_2_release_notes.html">Ruby on Rails 3.2 发布记</a></dd>
                <dd><a href="3_1_release_notes.html">Ruby on Rails 3.1 发布记</a></dd>
                <dd><a href="3_0_release_notes.html">Ruby on Rails 3.0 发布记</a></dd>
                <dd><a href="2_3_release_notes.html">Ruby on Rails 2.3 发布记</a></dd>
                <dd><a href="2_2_release_notes.html">Ruby on Rails 2.2 发布记</a></dd>
              </dl>
          </div>
        </li>
        <li><a class="nav-item" href="contributing_to_ruby_on_rails.html">贡献</a></li>
        <li><a class="nav-item" href="credits.html">感谢</a></li>
        <li class="guides-index guides-index-small">
          <select class="guides-index-item nav-item">
            <option value="index.html">指南索引</option>
              <optgroup label="新手入门">
                  <option value="getting_started.html">Rails 入门</option>
              </optgroup>
              <optgroup label="模型">
                  <option value="active_record_basics.html">Active Record 基础</option>
                  <option value="active_record_migrations.html">Active Record 迁移</option>
                  <option value="active_record_validations.html">Active Record 数据验证</option>
                  <option value="active_record_callbacks.html">Active Record 回调</option>
                  <option value="association_basics.html">Active Record 关联</option>
                  <option value="active_record_querying.html">Active Record 查询接口</option>
              </optgroup>
              <optgroup label="视图">
                  <option value="layouts_and_rendering.html">Rails 布局和视图渲染</option>
                  <option value="form_helpers.html">Action View 表单辅助方法</option>
              </optgroup>
              <optgroup label="控制器">
                  <option value="action_controller_overview.html">Action Controller 概览</option>
                  <option value="routing.html">Rails 路由全解</option>
              </optgroup>
              <optgroup label="深入探索">
                  <option value="active_support_core_extensions.html">Active Support 核心扩展</option>
                  <option value="i18n.html">Rails 国际化 API</option>
                  <option value="action_mailer_basics.html">Action Mailer 基础</option>
                  <option value="active_job_basics.html">Active Job 基础</option>
                  <option value="testing.html">Rails 应用测试指南</option>
                  <option value="security.html">Ruby on Rails 安全指南</option>
                  <option value="debugging_rails_applications.html">调试 Rails 应用</option>
                  <option value="configuring.html">配置 Rails 应用</option>
                  <option value="command_line.html">Rails 命令行</option>
                  <option value="asset_pipeline.html">Asset Pipeline</option>
                  <option value="working_with_javascript_in_rails.html">在 Rails 中使用 JavaScript</option>
                  <option value="autoloading_and_reloading_constants.html">自动加载和重新加载常量</option>
                  <option value="caching_with_rails.html">Rails 缓存概览</option>
                  <option value="api_app.html">使用 Rails 开发只提供 API 的应用</option>
                  <option value="action_cable_overview.html">Action Cable 概览</option>
              </optgroup>
              <optgroup label="扩展 Rails">
                  <option value="rails_on_rack.html">Rails on Rack</option>
                  <option value="generators.html">创建及定制 Rails 生成器和模板</option>
              </optgroup>
              <optgroup label="为 Ruby on Rails 做贡献">
                  <option value="contributing_to_ruby_on_rails.html">为 Ruby on Rails 做贡献</option>
                  <option value="api_documentation_guidelines.html">API 文档指导方针</option>
                  <option value="ruby_on_rails_guides_guidelines.html">Ruby on Rails 指南指导方针</option>
              </optgroup>
              <optgroup label="维护方针">
                  <option value="maintenance_policy.html">Ruby on Rails 的维护方针</option>
              </optgroup>
              <optgroup label="发布记">
                  <option value="upgrading_ruby_on_rails.html">Ruby on Rails 升级指南</option>
                  <option value="5_0_release_notes.html">Ruby on Rails 5.0 发布记</option>
                  <option value="4_2_release_notes.html">Ruby on Rails 4.2 发布记</option>
                  <option value="4_1_release_notes.html">Ruby on Rails 4.1 发布记</option>
                  <option value="4_0_release_notes.html">Ruby on Rails 4.0 发布记</option>
                  <option value="3_2_release_notes.html">Ruby on Rails 3.2 发布记</option>
                  <option value="3_1_release_notes.html">Ruby on Rails 3.1 发布记</option>
                  <option value="3_0_release_notes.html">Ruby on Rails 3.0 发布记</option>
                  <option value="2_3_release_notes.html">Ruby on Rails 2.3 发布记</option>
                  <option value="2_2_release_notes.html">Ruby on Rails 2.2 发布记</option>
              </optgroup>
          </select>
        </li>
      </ul>
    </div>
  </div>
  <hr class="hide" />

  <div id="feature">
    <div class="wrapper">
      <h2>Ruby on Rails 指南指导方针</h2><p>本文说明编写 Ruby on Rails 指南的指导方针。本文也遵守这一方针，本身就是个示例。</p><p>读完本文后，您将学到：</p>
<ul>
<li>  Rails 文档使用的约定；</li>
<li>  如何在本地生成指南。</li>
</ul>


              <div id="subCol">
          <h3 class="chapter"><img src="images/chapters_icon.gif" alt="" />目录</h3>
          <ol class="chapters">
<li><a href="#markdown">Markdown</a></li>
<li><a href="#prologue">序言</a></li>
<li><a href="#headings">标题</a></li>
<li><a href="#linking-to-the-api">指向 API 的链接</a></li>
<li><a href="#ruby-on-rails-guides-guidelines-api-documentation-guidelines">API 文档指导方针</a></li>
<li>
<a href="#html-guides">HTML 版指南</a>

<ul>
<li><a href="#html-guides-generation">生成</a></li>
<li><a href="#validation">验证</a></li>
</ul>
</li>
<li>
<a href="#kindle-guides">Kindle 版指南</a>

<ul>
<li><a href="#kindle-guides-generation">生成</a></li>
</ul>
</li>
</ol>

        </div>

    </div>
  </div>

  <div id="container">
    <div class="wrapper">
      <div id="mainCol">
        <p><a class="anchor" id="markdown"></a></p><h3 id="markdown">1 Markdown</h3><p>指南使用 <a href="https://help.github.com/articles/github-flavored-markdown">GitHub Flavored Markdown</a> 编写。Markdown 有<a href="http://daringfireball.net/projects/markdown/syntax">完整的文档</a>，还有<a href="http://daringfireball.net/projects/markdown/basics">速查表</a>。</p><p><a class="anchor" id="prologue"></a></p><h3 id="prologue">2 序言</h3><p>每篇文章的开头要有介绍性文字（蓝色区域中的简短介绍）。序言应该告诉读者文章的主旨，以及能让读者学到什么。可以以<a href="routing.html">Rails 路由全解</a>为例。</p><p><a class="anchor" id="headings"></a></p><h3 id="headings">3 标题</h3><p>每篇文章的标题使用 <code>h1</code> 标签，文章中的小节使用 <code>h2</code> 标签，子节使用 <code>h3</code> 标签，以此类推。注意，生成的 HTML 从 <code>&lt;h2&gt;</code> 标签开始。</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
Guide Title
===========

Section
-------

### Sub Section

</pre>
</div>
<p>标题中除了介词、连词、冠词和“to be”这种形式的动词之外，每个词的首字母大写：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
#### Middleware Stack is an Array
#### When are Objects Saved?

</pre>
</div>
<p>行内格式与正文一样：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
##### The `:content_type` Option

</pre>
</div>
<p><a class="anchor" id="linking-to-the-api"></a></p><h3 id="linking-to-the-api">4 指向 API 的链接</h3><p>指南生成程序使用下述方式处理指向 API（<code>api.rubyonrails.org</code>）的链接。</p><p>包含版本号的链接原封不动。例如，下述链接不做修改：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
http://api.rubyonrails.org/v5.0.1/classes/ActiveRecord/Attributes/ClassMethods.html

</pre>
</div>
<p>请在发布记中使用这种链接，因为不管生成哪个版本的指南，发布记中的链接不应该变。</p><p>如果链接中没有版本号，而且生成的是最新开发版的指南，域名会替换成 <code>edgeapi.rubyonrails.org</code>。例如：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
http://api.rubyonrails.org/classes/ActionDispatch/Response.html

</pre>
</div>
<p>会变成：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
http://edgeapi.rubyonrails.org/classes/ActionDispatch/Response.html

</pre>
</div>
<p>如果链接中没有版本号，而生成的是某个版本的指南，会在链接中插入版本号。例如，生成 v5.1.0 的指南时，下述链接：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
http://api.rubyonrails.org/classes/ActionDispatch/Response.html

</pre>
</div>
<p>会变成：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
http://api.rubyonrails.org/v5.1.0/classes/ActionDispatch/Response.html

</pre>
</div>
<p>请勿直接链接到 <code>edgeapi.rubyonrails.org</code>。</p><p><a class="anchor" id="ruby-on-rails-guides-guidelines-api-documentation-guidelines"></a></p><h3 id="ruby-on-rails-guides-guidelines-api-documentation-guidelines">5 API 文档指导方针</h3><p>指南和 API 应该连贯一致。尤其是<a href="api_documentation_guidelines.html">API 文档指导方针</a>中的下述几节，同样适用于指南：</p>
<ul>
<li>  <a href="api_documentation_guidelines.html#wording">用词</a>
</li>
<li>  <a href="api_documentation_guidelines.html#english">英语</a>
</li>
<li>  <a href="api_documentation_guidelines.html#example-code">示例代码</a>
</li>
<li>  <a href="api_documentation_guidelines.html#file-names">文件名</a>
</li>
<li>  <a href="api_documentation_guidelines.html#fonts">字体</a>
</li>
</ul>
<p><a class="anchor" id="html-guides"></a></p><h3 id="html-guides">6 HTML 版指南</h3><p>在生成指南之前，先确保你的系统中安装了 Bundler 的最新版。写作本文时，要在你的设备中安装 Bundler 1.3.5 或以上版本。</p><p>安装最新版 Bundler 的方法是，执行 <code>gem install bundler</code> 命令。</p><p><a class="anchor" id="html-guides-generation"></a></p><h4 id="html-guides-generation">6.1 生成</h4><p>若想生成全部指南，进入 <code>guides</code> 目录，执行 <code>bundle install</code> 命令之后再执行：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
$ bundle exec rake guides:generate

</pre>
</div>
<p>或者</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
$ bundle exec rake guides:generate:html

</pre>
</div>
<p>得到的 HTML 文件在 <code>./output</code> 目录中。</p><p>如果只想处理 <code>my_guide.md</code>，使用 <code>ONLY</code> 环境变量：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
$ touch my_guide.md
$ bundle exec rake guides:generate ONLY=my_guide

</pre>
</div>
<p>默认情况下，没有改动的文章不会处理，因此实际使用中很少用到 <code>ONLY</code>。</p><p>如果想强制处理所有文章，传入 <code>ALL=1</code>。</p><p>如果想生成英语之外的指南，可以把译文放在 <code>source</code> 中的子目录里（如 <code>source/es</code>），然后使用 <code>GUIDES_LANGUAGE</code> 环境变量：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
$ bundle exec rake guides:generate GUIDES_LANGUAGE=es

</pre>
</div>
<p>如果想查看可用于配置生成脚本的全部环境变量，只需执行：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
$ rake

</pre>
</div>
<p><a class="anchor" id="validation"></a></p><h4 id="validation">6.2 验证</h4><p>请使用下述命令验证生成的 HTML：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
$ bundle exec rake guides:validate

</pre>
</div>
<p>尤其要注意，ID 是从标题的内容中生成的，往往会重复。生成指南时请设定 <code>WARNINGS=1</code>，监测重复的 ID。提醒消息中有建议的解决方案。</p><p><a class="anchor" id="kindle-guides"></a></p><h3 id="kindle-guides">7 Kindle 版指南</h3><p><a class="anchor" id="kindle-guides-generation"></a></p><h4 id="kindle-guides-generation">7.1 生成</h4><p>如果想生成 Kindle 版指南，使用下述 Rake 任务：</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
$ bundle exec rake guides:generate:kindle

</pre>
</div>


        <h3>反馈</h3>
        <p>
          我们鼓励您帮助提高本指南的质量。
        </p>
        <p>
          如果看到如何错字或错误，请反馈给我们。
          您可以阅读我们的<a href="http://edgeguides.rubyonrails.org/contributing_to_ruby_on_rails.html#contributing-to-the-rails-documentation">文档贡献</a>指南。
        </p>
        <p>
          您还可能会发现内容不完整或不是最新版本。
          请添加缺失文档到 master 分支。请先确认 <a href="http://edgeguides.rubyonrails.org">Edge Guides</a> 是否已经修复。
          关于用语约定，请查看<a href="ruby_on_rails_guides_guidelines.html">Ruby on Rails 指南指导</a>。
        </p>
        <p>
          无论什么原因，如果你发现了问题但无法修补它，请<a href="https://github.com/rails/rails/issues">创建 issue</a>。
        </p>
        <p>
          最后，欢迎到 <a href="http://groups.google.com/group/rubyonrails-docs">rubyonrails-docs 邮件列表</a>参与任何有关 Ruby on Rails 文档的讨论。
        </p>
        <h4>中文翻译反馈</h4>
        <p>贡献：<a href="https://github.com/ruby-china/guides">https://github.com/ruby-china/guides</a>。</p>
      </div>
    </div>
  </div>

  <hr class="hide" />
  <div id="footer">
    <div class="wrapper">
      <p>本著作采用 <a href="https://creativecommons.org/licenses/by-sa/4.0/">创作共用 署名-相同方式共享 4.0 国际</a> 授权</p>
<p>“Rails”，“Ruby on Rails”，以及 Rails Logo 为 David Heinemeier Hansson 的商标。版权所有</p>

    </div>
  </div>

  <script type="text/javascript" src="javascripts/jquery.min.js"></script>
  <script type="text/javascript" src="javascripts/responsive-tables.js"></script>
  <script type="text/javascript" src="javascripts/guides.js"></script>
  <script type="text/javascript" src="javascripts/syntaxhighlighter.js"></script>
  <script type="text/javascript">
    syntaxhighlighterConfig = {
      autoLinks: false,
    };
    $(guidesIndex.bind);
  </script>
</body>
</html>
